Wave Player Element

Modified on 2018/07/16 01:56 by Administrator Categorized as Auditory Stimuli, Base Elements, Elements
<div style="margin-right: 10px; margin-left: 16px; margin-bottom:10px; float: right; width: 500px; overflow: hidden; height: auto; padding: 0px; background: #fafafa; background: -webkit-gradient(linear, left top, left bottom, from(#fbfbfb), to(#fafafa));background: -moz-linear-gradient(top, #fbfbfb, #fafafa);border: 1px dashed #ddd;box-shadow: 0 0 0 3px #fff, 0 0 0 5px #ddd, 0 0 0 10px #fff, 0 0 2px 10px #eee;">
== Summary ==
{s:Element Info Panel
| title=Wave Player
| category=Audio Stimuli
| icon=[image|Element Icon|{UP(Wave Player Element)}Wave-Player-Element-Icon.png]
| author= OkazoLab
| addin= Base Layer
| scope= Parent event
| usage= Snippets
| ownsnippets= None
}
== Properties ==
{|
|-
! Name
! Description                              
! Constraints
! Type
! On<br/>runtime<br/>change
|-
| colspan="5" bgcolor="#AADDDDD" | Hardware Settings
|-
| Playback API        
| Defines API for the audio playback. WASAPI is not supported in Windows XP but can be the best choice in Windows Vista and higher. ASIO API may require hardware that support it and appropriate drivers.        
| {s:atDesign}        
| stSoun..        
|  
|-
| Sound Device        
| Defines a sound device for the audio playback, when multiple devices are available in the system. Different playback APIs return their own device list for selection        
| {s:atDesign}        
| Int32        
|  
|-
| WASAPI Share Mode        
| Defines whether the selected sound device will be used in the shared or exclusive mode. This setting is relevant only when WASAPI is chosen. The exclusive mode greatly improves timing accuracy of audio playback and is recommended for stimulus presentation. As a drawback, only one Wave Player element per experiment can access the particular sound device in the exclusive mode.        
| {s:atDesign}        
| AudioC..        
|  
|-
| ASIO Control Panel        
| Opens a control panel with ASIO driver settings        
| {s:atRuntimeAction}        
| Boolean        
|  
|-
| Buffer Latency        
| Defines the size of the internal audio buffer (in ms), where wave data is loaded just before playback. Small buffers may cause CPU overhead, but guarantee faster playback adjustments, e.g. for the volume. Large buffers usually are better for smooth playback. The typical range for the property value is between 25- 500 ms.  The property value is ignored when ASIO API is used.        
| {s:atDesign}        
| Int32        
|  
|-
| Test Playback        
| Initiates a single playback of the currently selected clip using the chosen hardware settings of the element. An error message is returned, if the playback is failed.        
| {s:atDesign}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Playback Settings
|-
| Playback Mode        
| Defines the playback mode for audio clips played by the element. In the default mode (Auto Playback), a clip is played once on the onset of the parent event. In the Manual mode the playback process is controlled in the snippets by changing the Is Playing property.        
| {s:atDesign}        
| stPlay..        
|  
|-
| Asynchronous Monitoring        
| Defines whether the element asynchronously monitors its own playback process. Enabling this property may allow more accurate detection of the end of the playback. As a drawback, monitoring may marginally impair the timing accuracy of the playback start and, therefore, is not recommended for precise stimulus presentation.        
| {s:atNormal}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Playback Controls
|-
| Current Clip Info        
| Returns a structure containing an info about the currently selected audio clip. Click to expand all fields.         
| {s:atStatus}        
| stWave..        
|  
|-
| Volume        
| Defines the playback volume, from the ground (0) to full (100) level        
| {s:atNormal}        
| Double        
|  
|-
| Balance        
| Defines the stereophonic balance, left (-100) to right (100) of the audio clip        
| {s:atNormal}        
| Int32        
|  
|-
| Start Position        
| Defines the start position of the further audio playbacks in percentages to the total duration of the currently selected audio clip.         
| {s:atNormal}        
| Double        
|  
|-
| Playing Position        
| Indicates the current playing position (in percentages to the total duration) of the audio clip. Changes are accepted only if the audio is currently playing.         
| {s:atNormal}        
| Double        
|  
|-
| Is Playing        
| Returns or sets the current playback state of the element. In the manual playback mode, the value can be set before the onset of the parent event. In all modes, the property can be used to control the currently playing audio: assigning false/true to the property causes pause/continuing the playback, correspondingly.        
| {s:atNormal}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Runtime Status
|-
| Triggering Time        
| Returns the local event time in ms, when the last playback has reached the end.        
| {s:atStatus}        
| clTime        
|  
|-
| Is Triggered        
| Indicates that the element has been triggered by end of the playback at least once, since the onset of the parent event.        
| {s:atNormal}        
| Boolean        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Material List
|-
| Selected Index        
| Defines an index of the active item in the material list of this element        
| {s:atNormal}        
| Int32        
|  
|-
| Selected Item        
| Defines a name if the active library item in the material list of this element        
| {s:atNormal}        
| String        
|  
|-
| Item Count        
| Returns the total number of material items in the list of this element        
| {s:atStatus}        
| Int32        
|  
|-
| colspan="5" bgcolor="#AADDDDD" | Control
|-
| Is Enabled        
| If set to false the element is completely omitted when the experiment is run        
| {s:atDesign}        
| Boolean        
|  
|-
| Title        
| Title of the element        
| {s:atDesign}        
| String        
|  
|-            
|}
== ==
</div>
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
<!--*****************************************************************************************************************************************************************************-->
'''Wave Player Element''' is capable of playing audio clips in the Wave format. The element is recommended for modern sound cards on Vista and Windows 7 system,when high temporal accuracy of audio playback is required. For Windows XP and old sound cards the Direct Sound element may produce better results after fine hardware tuning. The Wave Player element allows to choose one of four audio playback API. Among them, WSAPI in the exclusive mode is recommended by default for the best temporal accuracy.{br}{br}
{TOC}

Wave Player is the default element in EventIDE for delivering audio stimuli that is stored in Wave format. It is recommended to use this element for modern sound cards on Windows Vista, Windows 7 & 8, when high temporal accuracy of audio playback is required. For Windows XP and old sound cards the Direct Sound element may produce more accurate results.

The Wave Player element allows one to select one of four audio playback API: [^http://en.wikipedia.org/wiki/DirectSound|DirectSound], WaveOut (also known as[http://msdn.microsoft.com/en-us/library/aa910179|Waveform Audio API]), [^http://en.wikipedia.org/wiki/Audio_Stream_Input/Output|ASIO] and [^http://msdn.microsoft.com/en-us/library/windows/desktop/dd371455%28v=vs.85%29.aspx|WASAPI].

In the most cases, WSAPI in the exclusive mode delivers the best temporal accuracy and fidelity of audio playback. (for example, the mid-range Creative SB X-Fi Titanium Professional card, used in Windows 7 & 8, allows to start a playback just in 2ms after onset of the parent event)

The Wave Player element allows the selection of the output sound device when multiple sound cards installed on a computer.

For some professional sound cards another low-level sound API,[http://en.wikipedia.org/wiki/Audio_Stream_Input/Output|Audio Stream Input/Output] ASIO, can be recommended. Using ASIO API and compatible sound hardware and drivers (the last two are essential) may also help to achieve perfect temporal precision and fidelity.

Wave Player element supports the majority of resolutions and encodings used in the Wave format. The element automatically converts input wave clips into uncompressed PCM data streams before a playback. Since the conversion takes some time, using the uncompressed PCM wave clips is recommended for faster processing of audio stimuli.

== Snapshots ==
{|
| [imageleft|Wave Player element is used in <br/> the 'media player' demo <br/> made with EventIDE|{UP}/pictures/Elements/waveplayer/small/smWavePlayer.png|{UP}/pictures/Elements/waveplayer/WavePlayer.png]
|}

== Element Demo ==
The 'WaveAudioPlayer' demo for the Wave Player element can be found online in the [ http://www.okazolab.com/experiment-gallery| Experiment Gallery]

== When using the Wave Player element ==

EventIDE provides several [elements|elements] for delivering auditory stimuli. The audio elements have similar functionality and a choice depends on design demands and the used sound hardware. A guidance on selecting an audio element is available in [Auditory stimuli] article.

In short, the Wave Player element is the simplest and most recommended audio element especially, if Windows Vista/7/8 OS and modern sound card are used.

== Playing a single audio file ==

If you want to play a simple audio tone of certain frequency and duration, you can use [http://www.wavtones.com/functiongenerator.php|this online audio generator] to get a wave file compatible with the Wave Player element. Once you download the generated file, add it into [Material Library] and then drag into the Wave Player element.

== Building an audio stimulus set ==

The Wave Player element can handle a stimulus set containing multiple audio clips. One of these clips can be then selected to be played in a single trial. To build a stimulus set, load selected audio clips from [Material Library] directly into the element (e.g. by drag-and-drop). Then use the Item Index property to select an audio clip for playback. It's recommended to change the Item Index property before the onset of the parent event, because preparing the clip for playback takes time.

== Practical Use ==

# Add a new Wave Player element into the selected event (where audio has to be played).
# Select the element in the [Element Panel], then its properties will appear in the [Property panel] on the right.
# Load selected audio clips from the Material Library to the item list of the element and select the current clip via Item Index property.
# Browse to the Hardware Settings group in the element properties and select Playback API and Sound Device in the corresponding properties.
# Select a playback mode for the element in the Playback Setting group. The most common mode for presentation of auditory stimulus is "Single playback on onset of the parent event"
# Test, if an audio is played by clicking over the Test Playback property.
# Make sure that duration of the parent event is greater or equal to duration of the selected audio clip- an audio playback is always aborted on offset of the parent event.

There are two typical scenario of using the element for presenting audio stimuli in multiple trials:

* If you want to present a random audio clip in each trial, use the 'Single playback' mode and add a [Proxy Variables|proxy] linked to the Item Index property. With that proxy you can select an audio clip from the element's list in code snippets (normally before onset of the parent event).
* If you want to chose whether an audio clip has to be played or not in each trial, select 'Manual' mode add a [Proxy Variables|proxy] linked to the Is Playing property. Setting that proxy to true/false in code snippets will allow to turn on/off audio playback on the onset of the parent event (the proxy has to be set before the onset).


== Playback modes ==

At runtime the element can work in 3 different playback modes, which define how playback process starts and stops. The mode has to be selected at design-time and cannot be changed. However, it's possible to use multiple elements working in different modes in parallel. The available modes are:

===Single playback on event onset===

In this mode the element starts to play an audio synchronously with activation of the parent event. The audio is played once. When the playback stops you can initiate a new one manually if the parent event is still active.

===Looped playback on event onset===

In this mode the element starts to play audio synchronously with activation of the parent event and automatically restarts the playback as soon as the end of the audio clip is reached. This playback loop lasts until deactivation of the parent event.

===Manual mode===

In this mode the playback is controlled solely by element's IsPlaying property, which can be changed in snippets. If IsPlaying is set to true before onset of the parent event, the playback behaviour will be similar to 'Single playback on event onset' mode. If the parent event is active, the playback starts/stops on a change of the IsPlaying property. The Is Playing property automatically turns to false when the playback ends.

== Triggering at the end of the playback ==

In some experimental scenarios it can be reasonable to end the parent event immediately after finishing a playback of the current audio. Since the same Wave Player element can switch between multiple audio clips of different durations, the duration of the parent event can not be set to a fixed value. The Wave Player elements offers an easy solution - the element monitors a playback process and gets triggered at the end of each audio clip. Triggering is followed by a call of the OnTriggered snippet, which can contain user programmed actions. In addition, the element has a boolean status property, called Is Triggered, which can be used directly to control the event flow in EventIDE.



== Notes ==

# The Wave Player element is optimized to deliver the best timing accuracy and fidelity of audio playback. However, it's always recommended to measure empirically the timing of the actual playback when high accuracy is required. The measurements can be done with oscilloscope connected to the output of the sound card and photo-diode on a monitor. Probing different settings of the element in such testing can help to achieve the optimal results.
# Slightly better onset of the audio playback can be achieved if the element is placed at the top of the elements list in the parent event. Elements in the list get activated one by one on the onset of the parent event, so the top position in the list will minimize the onset delay.
Meta Keywords: audio stimuli, EventIDE, Okazolab, wave player
Meta Description:
Change Comment:
EventIDE Wiki

Navigation¶

Wave Player Element
